In Tycho, documentation and design are integrated. Hyperlinks can bind pretty much anything to anything. For formatted text, Tycho uses HTML, the hypertext markup language of the internet. Formatted text can appear in any Tycho widget.
The HTML widget in Tycho is based on the HTML library written by Stephen Uhler of Sun Microsystems, which supports all the features of HTML 2.0. There is currently no support in Tycho for HTTP hyperlink references, so you cannot within Tycho directly read documents on the internet. A sample document illustrates the HTML tags that are supported.
In Tycho, documentation files are kept small. This helps the response time of parser (which is really quite slow) and keeps information modular. Hyperlinks are used extensively throughout. An HTML editor provides support for hyperlinks, including a utility for checking their validity.
One key extension to HTML provided by Tycho allows embedding Tcl scripts into a document in such a manner that if the user double clicks on the script, the script will be executed. The HTML source for such a script is surrounded by by the delimitters <tcl> and </tcl>. For example, the HTML source
<pre><tcl> ::tycho::post "hello world" </pre></tcl>appears as follows in a document:
Double clicking on this script will execute it if you are viewing the document under Tycho.::tycho::post "hello world"
A major feature of the Tycho integrated documentation system is its ability to automatically generate and maintain indexes. Effective use of this feature requires some discipline in writing the HTML documents in the first place.
Index entries are constructed from anchors with a name attribute. For example, the source for the previous sentence is
Index entries are constructed from <a name=anchors>anchors</a> with a <a name="name attribute">name attribute</a>.When an index is created from this document, the value of the name attribute will appear in the index with a pointer to precisely this point in the document. Thus, for example, the Tycho master index has a pointer to the above sentence under both "anchors" and "name attribute". Try it:
Notice that the name attribute can (an often should) have spaces in it. It must be surrounded by quotation marks if it has spaces in it.::tycho::File::openContext $TYCHO/tycho.idx
Given one or more HTML documents, you can create an index for them
using the tychoMkIndex
Tcl command
(you can invoke this in the console window).
This command takes three or more arguments.
The first argument is the name of the index, which will appear at the
top of the index browser.
The second argument is the name of the index file to create.
This file should have the extension ".idx" so that it will be recognized
as an index file.
The rest of the arguments are any number of HTML file names
from which the index should be created.
Instead of listing many files, you can use glob patterns like "*.html"
for the file names. A glob pattern can contain
wildcards like "*", which match zero or more characters of any type.
Once you have created an index and stored it in a file with the extension ".idx", that file will be opened using an index browser.